Stop

Tour objects passed to PTV Drive&Arrive contains several stops. PTV Drive&Arrive supplies the following functions to get, modify or remove information of stops.

/stop/ GET - read details of stop with the specified SCEM-ID

Get information about a stop referenced by an SCEM-ID via https://driveandarrive-v1.cloud.ptvgroup.com/em/stop?SCEMID=X9X9X9X9X9&source=<myProduct_Vx.y> will return the following response:

{
  "stop": 
  {
    "coordinate": {
      "locationX": 8.000,
      "locationY": 49.000
    },
    "earliestArrivalTime": "YYYY-MM-DDThh:mm:ss.0000000+01:00", 
    "latestDepartureTime": "YYYY-MM-DDThh:mm:ss.0000000+01:00", 
    "pta": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
    "serviceTimeAtStop": 0,
    "useServicePeriodForRecreation": true,
    "weightWhenLeavingStop": 0,
	"locationId": "",
	"useLocationAddress": false,
	"address": {
	  "label":"",
  	  "country": "",
	  "state": "",
	  "province": "",
	  "postCode": "",
	  "city": "",
	  "city2": "",
	  "street": "",
	  "houseNumber": ""
	}
    "customData": {},
    "scemid": "X9X9X9X9X9"
  },
  "responseStatus": 
  {
    "errorCode": "SUCCESS",
    "message": "000000000000"
  }
}
		

Exceptions

validation / message	errorCode
SCEM-ID not valid. SCEM-ID should be a 10-digit, case-sensitive, alphanumeric identifier of an existing stop.	SCEMID_INVALID

/stop/batch/ DELETE - delete multiple stops which belong to the specified SCEM-IDs

The call to https://driveandarrive-v1.cloud.ptvgroup.com/em/stop/batch?token=<token>&SCEMIDS=<SCEMID1,SCEMID2, ...>&source=<myProduct_Vx.y> deletes a specific stop within a tour and returns the following response:

{
  "responseStatus": 
  {
    "errorCode": "SUCCESS",
    "message": "000000000000"
  }
}
		

When deleting a stop all subscriptions to this stop will be removed automatically.

Exceptions

validation / message	errorCode
SCEM-ID not valid. SCEM-ID should be a 10-digit, case-sensitive, alphanumeric identifier of an existing stop.	SCEMID_INVALID
Token does not exist.	TOKEN_ERROR
Delete stops failed. In a resulting tour with 2 stops, the stop coordinates need to be different.	2_STOP_TOUR_REQUIRES_DIFF_COORDINATES

/stop/batch/ GET - read multiple stops which belong to the specified SCEM-IDs

The call https://driveandarrive-v1.cloud.ptvgroup.com/em/stop/batch?token=<token>&SCEMIDS=<SCEMID1,SCEMID2, ...>&source=<myProduct_Vx.y> reads multiple stops that are listed in the SCEMIDS list.

The SCEMIDs list can contain multiple stop scemids or a tour scemid. When a tour scemid is provided, all stops from the tour are returned in response.
Currently only reading stops from a single tour is allowed.

{
  "stops": 
  [
    {
      "coordinate": 
      {
        "locationX": 8.000,
        "locationY": 50.000
      },
      "earliestArrivalTime": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
      "latestDepartureTime": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
      "pta": "YYYY-MM-DDThh:mm:ss.0000000+01:00", 
      "serviceTimeAtStop": 0,
      "useServicePeriodForRecreation": true,
      "weightWhenLeavingStop": 0,
      "customData": {},
      "scemid": "X8X8X8X8X8"
    },
    {...},
    {
        "coordinate":
		{
          "locationX": 8.000,
          "locationY": 50.000
        },
        "earliestArrivalTime": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
        "latestDepartureTime": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
        "pta": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
        "serviceTimeAtStop": 0,
        "useServicePeriodForRecreation": true,
        "weightWhenLeavingStop": 0,
        "customData": {},
        "scemid": "X9X9X9X9X9"
    }
  ],
  "responseStatus": 
  {
    "errorCode": "SUCCESS",
    "message": "000000000000"
  }
}
		

Exceptions

validation / message	errorCode
SCEM-ID not valid. SCEM-ID should be a 10-digit, case-sensitive, alphanumeric identifier of an existing stop.	SCEMID_INVALID
Token <token> does not exist	TOKEN_ERROR
Token <token> is blocked. Please contact support in order to get further information.	TOKEN_BLOCKED
The validation date of token <token> is expired.	TOKEN_EXPIRED
Error(s) occured during stop batch read operation.	ERROR_READ_STOP_BATCH
SCEMIDS contains both tour and stop scemids. Use either a tour or stop scemid(s).	BOTH_TOUR_AND_STOP_SCEMID_FOUND
Currently reading stops is only supported from a single tour.	INVALID_TOUR_COUNT

/stop/batch/ PUT - update multiple stops which belong to the specified SCEM-IDs

This PUT method with URL https://driveandarrive-v1.cloud.ptvgroup.com/em/stop/batch?token=<token>&source=<myProduct_Vx.y> will update the entire data of a stop, e.g. earliest arrival, latest departure and service time at stop and other parameters.

{
  "stops": 
  [
    {
      "coordinate": 
      {
        "locationX": 9.194666,
        "locationY": 48.691846
      },
      "earliestArrivalTime": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
      "latestDepartureTime": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
      "pta": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
      "stopPositionInTour" : 3,
      "serviceTimeAtStop": 0,
      "useServicePeriodForRecreation": true,
      "weightWhenLeavingStop": 0,
      "customData": {},
      "scemid": "X9X9X9X9X9"
    }
  ]
}
		

Updates of a specific stop can be lead to notifications.

Result

{
  "responseStatus": 
  {
    "errorCode": "SUCCESS",
    "message": "000000000000"
  }
}
		

Exceptions

validation / message	errorCode
Token does not exist.	TOKEN_ERROR
A duplicated StopPositionInTour is not valid.	ERR_MESSAGE_DUPLICATE_STOPPOSITIONINTOUR
Tour start cannot be n days in the future. [YYYY-MM-DDThh:mm:ss.0000000+01:00]	INVALID_TOUR_START_DATETIME
Maximum allowed tour duration of n days from [YYYY-MM-DDThh:mm:ss.0000000+01:00] has been exceeded.	TOUR_DURATION_EXCEEDED
Tour update quota has been reached. Please try again later.	TOUR_UPDATE_QUOTA_FULL

Calling limitations

In order to prevent misuse of tour change requests by bypassing new tours with https://driveandarrive-v1.cloud.ptvgroup.com/em/tour/ POST, Drive&Arrive imposes following limitation on tour/stop update calls: maximum of 200 tour or stops updates can be made in 24 hours interval.

This limitation can be configured as desired and set per token. If you need more quota for tour update requests, please contact our support.

 

/stop/batch/eta/ GET - get the current ETAs by the specified SCEM-IDs instead of getting notified

The call to https://driveandarrive-v1.cloud.ptvgroup.com/em/stop/batch/eta?SCEMIDs=X1X1X1X1X1,X8X8X8X8X8,X9X9X9X9X9&source=<myProduct_Vx.y> will return ETAs of the specified stops.

Token parameter is not necessary anymore.

on valid SCEMIDs, the "stopTimeInfos" attrribute in response contains following ETA information.

Example call: https://driveandarrive-v1.cloud.ptvgroup.com/em/stop/batch/eta?SCEMIDs=35ULSDW7EX,CU8PJL4GH82

{
  "stopTimeInfos": [
    {
      "stopSCEMID": "35ULSDW7EX",
      "plannedETA": "2019-06-27T10:37:29.9301908+02:00",
      "eta": "2019-06-27T11:25:54.0000000+02:00",
      "etaSource": "CALCULATE_POS_ETA",
      "relatedTime": "2019-06-27T10:38:35.2456768+02:00",
      "trafficTimeLoss": 871,                             // total delay on route
      "breakAndRestPeriod": 0,                            // total allowed break and rest time till this stop
      "waitingPeriod": 0,                                 // total waiting time (not used for recreation or service times)
      "lastState": "APPROACHING"
    },
    {
      "stopSCEMID": "U8PJL4GH82",
      "plannedETA": "2019-06-27T12:37:29.9311893+02:00",
      "eta": "2019-06-27T13:04:49.0000000+02:00",
      "etaSource": "CALCULATE_POS_ETA",
      "relatedTime": "2019-06-27T10:38:35.2456768+02:00",
      "trafficTimeLoss": 871,
      "breakAndRestPeriod": 900,
      "waitingPeriod": 0,
    }
  ],
  "responseStatus": {
    "errorCode": "SUCCESS",
    "message": "29ff988e-2a1b-44a0-91df-aa79008f52cf"
  }
}

stopTimeInfos[x].info

info field in stopTimeInfos hints on additional information on how the eta was calculated.

{
  "stopTimeInfos": [
    {
      "stopSCEMID": "GPU5MWS7FQ",
      "plannedETA": "2019-09-18T02:00:00.0000000+00:00",
      "eta": "2019-09-18T04:20:06.0000000+02:00",
      "etaSource": "CALCULATE_POS_ETA",
      "relatedTime": "2019-09-18T04:00:00.0000000+02:00",
      "trafficTimeLoss": -572,
      "breakAndRestPeriod": 0,
      "waitingPeriod": 0,
      "lastState": "APPROACHING",
      "info": "traffic information excluded due to inaccessible route sections"
    }
  ],
  "responseStatus": {
    "errorCode": "SUCCESS",
    "message": "77534a23-97ba-45b5-8619-aacc00f4f20d"
  }
}
		

ETA on arrived status

ETA for an arrived stop after an arrived event will be the time stamp of the sent event. Source will be STATUS_POS.

{
  "stopSCEMID": "X1X1X1X1X1",
  "plannedETA": "YYYY-MM-DDThh:mm:ss.0000000+01:00",  	// ETA as it is specified in the uploaded tour (EarliestArrivalTime or PTA, if set).
  "eta": "YYYY-MM-DDThh:mm:ss.0000000+01:00",         	// time stamp of arrived event for the stop
  "etaSource": "STATUS_POS",               		// source after an arrived event
  "relatedTime": "YYYY-MM-DDThh:mm:ss.0000000+01:00", 	// Time of the event which was responsible for the ETA calculation. PosEvent->PositionTime, TourCreated-> TourCreationTime
  "lastState": "ARRIVED"
}
		

The parameter etaSource changes on various situation during the active tour period. Following etaSource values are available:

• PLANNED_TOUR_ETA
This ETA comes from planned ETA before any ETA calculation takes place. The ETA information is taken from PTA or available earliestArrivalTime of tour stops.
• CALCULATE_REFROUTE_ETA
This ETA comes from the reference ETA calulation of a tour. The reference ETA is calculated on tour creation and tour updates unless otherwise stated in tour options.
• CALCULATE_POS_ETA
This ETA is calculated considering the position of the vehicle that was sent to DriveAndArrive event api. This is the expected realtime ETA and should be considered as the usable ETA for the stop.
• STATUS_POS
On arrival to a stop, the ETA will be changed to the arrival time and the etaSource to STATUS_POS.

The etaSource should be stated when visualising stop ETA. CALCULATE_REFROUTE_ETA should only be used for reference.

Exceptions

validation / message	errorCode
SCEM-ID not valid. SCEM-ID should be a 10-digit, case-sensitive, alphanumeric identifier of an existing stop. <[ERROR_SCEMIDS]>	SCEMID_INVALID

/stop/search POST - search stops to a location using customer identifier

The call to https://driveandarrive-v1.cloud.ptvgroup.com/em/stop/search?locationid=XLOCATIONIDXXXXXX&token=XXXTOKENXXXXXXXXX&source=ZZZZ

{
  "SearchFieldContent": {
    "SearchFields": [
      {
        {"fieldName":"customId","fieldValue":"01234567"},
        {"fieldName":"pin","fieldValue":"0123"}
      }
    ]
  }
}
}

returns stops having locationID and matching the given search fields. A corresponding error message with error code is shown on error. See error responses for detailed error messages.

Exceptions

validation / message	errorCode
LocationID should not be empty.	NotNull
SearchFieldContent should not be empty.	NotNull
SearchFields is missing or empty.	SEARCH_FIELD_CONTENT_INVALID
Location-ID not valid. Location should be a 25-digit, case-sensitive, alphanumeric identifier of a location.	LOCATION_ID_INVALID
The location does not exist (for this token).	LOCATION_ERROR
Token does not exist.	TOKEN_ERROR